Skip to main content

Configuration

An example configuration is shown below. The configuration should be supplied when calling the datawollet.initialise function. The web library will not interact with the page in any way if the datawollet.initialise function is not called, or if the initialisation conditions are not met.

The datawollet namespace global is injected when the library is loaded. You can use its presence to detect whether the library loaded successfully or not.

Example configuration
datawollet.initialise({
  logLevel: 'debug',

  conditions: {
    initialise: {
      ios: {
        safari: '>=16.4',
        chrome: '>=89',
      },
      desktop: {}
    }
  },

  api: {
    key: 'aaaaaaaaaaaaaaa', // DataWollet will provide this
  },

  session: {
    timeout: 3600000
  },

  sources: {
    confirmDeletion: true,
    allowUnexpected: true,
    expect: {
      documentClass: [
        'identity-passport',
        'identity-driving-licence',
      ],
      documentNodesTest: (n) => !!n.some(n.type === 'ark:FuzzyPerson')
    }
  },

  interface: {
    format: 'inline',
    position: () => ({
      before: document.querySelector('#container > div:first-of-type'),
    }),
    delayIdle: 2500,
    collapseOn: {
      minExpectedFills: 15
    }.
    html: {
      cover: `
        <p class="dw-visible-when--activity--uploading">Uploading document...</p>
        <p class="dw-visible-when--activity--prefilling dw-visible-when--activity--filling dw-visible-when--activity--idle"><span data-dw-data="fill.expected">...</span> questions answered...</span>
        <div class="dw-visible-when--activity--uploading dw-visible-when--activity--prefilling"></div>
        <div class="dw-visible-when--activity--idle dw-visible-when--activity--filling"></div>
      `,
      header: `
        <p>Use your documents to fill in this form.</p>
      `,
      instructions: `
        <p class="dw-visible-when--sources--none">Upload an identity document. We'll use it to fill in the form for you.</p>
        <p class="dw-visible-when--sources--some">Add more documents to fill in more of the form.</p>
      `,
      dropzoneStart: `
        <div class="dw-visible-when--error">
          <p class="dw-visible-when--error--file-type">Wrong file type.</p>
          <p class="dw-visible-when--error--file-parse">Couldn't parse that file.</p>
          <p class="dw-visible-when--error--file-size">File too large.</p>
          <p class="dw-visible-when--error--source-unrecognised">Unrecognised type of document.</p>
          <p class="dw-visible-when--error--source-unmatched"Can't read that specific document format yet.</p>
          <p class="dw-visible-when--error--source-lacking">Couldn't find any usable data in that document.</p>
          <p class="dw-visible-when--error--server-error">Something else went wrong.</p>
          <p class="dw-visible-when--error--server-timeout">Uploading timed out, try again.</p>
          <p class="dw-visible-when--error--server-forbidden">Server couldn't read that document for you.</p>
          <p class="dw-visible-when--error--scan-permission">Permission to use the camera to scan wasn't granted.</p>
          <p class="dw-visible-when--error--scan-quality">Bad quality scan, try again.</p>
        </div>
      `,
      dropzoneEnd: `
        <div class="dw-visible-when--error">
          <p class="dw-visible-when--error--scan-capability">Camera scanning isn't available.</p>
        </div>
      `,
      dropzoneDrag: `
        <p class="dw-visible-when--drop--permitted">Drop the document here</p>
        <p class="dw-visible-when--drop--invalid">That's not a PDF file, try another one.</p>
      `,
      footnotes: `
        <button class="dw-controller-inline-content-button" data-dw-action="collapse">
          Close
        </button>
      `,
      footer: `
        <p>Check out <a href="#">DataWollet's privacy policy</a> for more information.</p>
      `,
    }
  }
});

Log level​

The logLevel can be set to error, warn, info, debug, or trace.

Log events are sent to the console. By default the library will not log any events to the console, so we recommend configuring a debug level to begin with.

Events with a level lower than or equal to the configured level will be sent to the console, for example info includes all messages at error, warn and info level.

The log level can also be changed after initialisation.

datawollet.setLogLevel('error' | 'warn' | 'info' | 'debug' | 'trace');

Conditions​

This section of the configuration defines preconditions for initialising the library. If one or more preconditions are not met, then the interface is never shown to the user and they be unaware of the web library.

Additional preconditions also apply that are not configurable, and are tested prior to showing the interface, for example the ability to access DataWollet's AI registry.

initialise​

An object containing keys for conditions that must be satisfied for the library to attempt to load and show the user interface. Keys can include browser names (e.g. chrome or firefox) with version constraints using similar notation to npm package constraints, for example ~ will match the third element of a browser version number only.

Operating systems (e.g. windows and macos) and platforms (e.g. mobile and desktop) can also be specified as keys, with an object as the value specifying additional constraints such as the browser to allow constraints to be combined together. An empty object is treated as non-matching (e.g. don't show on desktop in the example above).

Internally, the constraints are evaluated using the frowser library and match the format documented there.

API​

An object containing the credentials to use for DataWollet's Data API services and the behaviour of the requests.

api: {
  key: "string",
  timeout?: "number",
  recipes?: {
    overrides?: {
      [recipeId: string]: "url"
    }
  }
}

key​

The API key supplied by DataWollet to access the Data API services. This is used for billing and tracking any usage constraints.

timeout​

The maximum allowed duration of API requests in milliseconds. Don't make this timeout too low as it applies to file uploads, and large documents may take several seconds to process fully, especially for camera scans and image inputs.

recipes​

Used internally by DataWollet to override the published auto-fill instructions and use an alternative source, as part of the development and testing process.

Session​

An object with configuration used to secure the sessions created by DataWollet to provide continuity between page loads or after refreshes.

session: {
  timeout?: "number"
  partitionBy?: "string" | (() => "string")
}

timeout​

The maximum duration of the session in milliseconds. The timeout is refreshed each time a valid request is made, such as after refreshing the page. Once the timeout has been exceeded, it is not possible to retrieve the results of any documents processed previously and the user should supply the documents again.

partitionBy​

A string value or a function returning a string, that is used to create a composite identifier for DataWollet sessions. This can be used to ensure DataWollet creates a new document processing session if your own web application creates a new session, if you ensure this string will change in those circumstances.

Sources​

An object with configuration used to define how data sources are handled, both when adding and removing.

sources?: {
  confirmDeletion?: "boolean"
  allowUnexpected?: "boolean"
  expect?: {
    documentClass?: "string[]"
    documentNodesTest?: "(n: Node) => boolean"
  }
}

confirmDeletion​

If set to true a confirmation modal is shown before the source is removed. The content of the modal can be customised using the HTML options in the interface section.

expect​

An object containing a single key documentClass, which should contain a string array for each document class to permit the user to use. The identifiers are the same as the classIdentifier in the Data API. New document types are added from time to time, the current list of possibilities includes:

  • identity-passport
  • identity-driving-licence
  • mortgage-statement
  • mortgage-illustration
  • mortgage-offer
  • property-energy-performance-certificate
  • property-freehold
  • property-leasehold
  • property-deed
  • property-tree-protection-order
  • property-council-tax-bill
  • property-tv-licence
  • tenancy-agreement
  • tenancy-deposit-protection-certificate
  • energy-statement
  • water-statement
  • insurance-policy-details
  • payments-direct-debit-instruction
  • telecoms-and-entertainment-bill
  • earnings-payslip

allowUnexpected​

If set to false then a document with a classification that isn't in the expected list above will not be added. If set to true then the source will be added but a warning can still be displayed. This allows alternative sources to be used for subsets of the data, for example if expecting an ID document for proof of address but able to accept a utility bill instead.

documentNodesTest​

If set with a function receiving an array of nodes, and returning a boolean, then it is used to test the graph data discovered in a source. If the function returns false then a source-expectations is raised, though it does not prevent the source from being added.

Interface​

An object with configuration for the user interface injected into the web page by the library.

interface: {
  timeout?: "number"
  format: "inline"
  brand?: "string"
  position: () => ({
    before?: "HTMLElement"
    after?: "HTMLElement"
    replace?: "HTMLElement"
    append?: "HTMLElement"
    prepend?: "HTMLElement"
  })
  delayIdle?: "number"
  collapseOn?: {
    minExpectedFills?: "number"
  }
  html?: {
    cover?: "string"
    header?: "string"
    instructions?: "string"
    dropzoneStart?: "string"
    dropzoneDrag?: "string"
    dropzoneEnd?: "string"
    footnotes?: "string"
    footer?: "string"
    confirmation?: "string"
  }
}

timeout​

The maximum duration to wait in milliseconds for injecting the user interface. This applies when the response from the position function does not contain an element that can be used to anchor the element, and therefore it is likely the page content is different to that which was expected.

format​

Only inline is supported at present, for a user interface embedded within the web page. Other options may be added later so we recommend configuring this value.

brand​

Used when DataWollet is providing a managed service, to specify a particular brand stylesheet and assets to be loaded. If self managing then you should host your own styles and assets instead.

position​

A callback function that should return exactly one key defining the position and the element desired for the interface to be injected at. The options are:

  • before the specified element
  • after the specified element
  • replace to replace the specified element altogether, such as when using a placeholder or fallback
  • append to add within a container at the end
  • prepend to add within a container at the beginning

delayIdle​

A duration in milliseconds to delay the state of the library transitioning to idle, which can be useful when displaying a success screen after reading or filling from a document.

collapseOn​

Automatically collapse the interface if the conditions specified are met. Current options include:

  • minExpectedFills to hide when the expected number of auto-completes is equal to or greater than this number

html​

An object containing strings that are injected within the user interface at the specified positions. See the documentation on customisation for more details.